/**
 * 监控接口定义
 * 基于 NestJS 官方示例实现
 * 参考: https://docs.nestjs.cn/fundamentals/dependency-injection
 * 对应 Java: 监控抽象
 */
export interface MonitoringInterface {
  /**
   * 记录计数器指标
   * @param name 指标名称
   * @param value 计数值
   * @param labels 标签
   */
  counter(name: string, value?: number, labels?: Record<string, string>): void;

  /**
   * 记录直方图指标
   * @param name 指标名称
   * @param value 值
   * @param labels 标签
   */
  histogram(name: string, value: number, labels?: Record<string, string>): void;

  /**
   * 记录摘要指标
   * @param name 指标名称
   * @param value 值
   * @param labels 标签
   */
  summary(name: string, value: number, labels?: Record<string, string>): void;

  /**
   * 记录仪表盘指标
   * @param name 指标名称
   * @param value 值
   * @param labels 标签
   */
  gauge(name: string, value: number, labels?: Record<string, string>): void;

  /**
   * 开始计时
   * @param name 计时器名称
   * @param labels 标签
   * @returns 计时器对象
   */
  startTimer(name: string, labels?: Record<string, string>): Timer;

  /**
   * 记录执行时间
   * @param name 指标名称
   * @param fn 要执行的函数
   * @param labels 标签
   * @returns 函数执行结果
   */
  time<T>(
    name: string,
    fn: () => T | Promise<T>,
    labels?: Record<string, string>,
  ): Promise<T>;

  /**
   * 获取指标值
   * @param name 指标名称
   * @param labels 标签
   * @returns 指标值
   */
  getMetric(
    name: string,
    labels?: Record<string, string>,
  ): Promise<number | null>;

  /**
   * 获取所有指标
   * @returns 指标数据
   */
  getMetrics(): Promise<string>;

  /**
   * 重置指标
   * @param name 指标名称
   */
  reset(name?: string): void;
}

/**
 * 计时器接口
 */
export interface Timer {
  /**
   * 结束计时
   * @param labels 标签
   */
  end(labels?: Record<string, string>): number;
}

/**
 * 健康检查接口
 */
export interface HealthCheckInterface {
  /**
   * 检查健康状态
   * @returns 健康状态
   */
  check(): Promise<HealthStatus>;

  /**
   * 注册健康检查
   * @param name 检查名称
   * @param checkFn 检查函数
   */
  register(name: string, checkFn: () => Promise<boolean>): void;

  /**
   * 取消注册健康检查
   * @param name 检查名称
   */
  unregister(name: string): void;
}

/**
 * 健康状态
 */
export interface HealthStatus {
  status: 'healthy' | 'unhealthy' | 'degraded';
  timestamp: number;
  uptime: number;
  checks: Record<string, HealthCheckResult>;
  version?: string;
  environment?: string;
}

/**
 * 健康检查结果
 */
export interface HealthCheckResult {
  status: 'pass' | 'fail' | 'warn';
  message?: string;
  timestamp: number;
  duration?: number;
}

/**
 * 性能监控接口
 */
export interface PerformanceMonitoringInterface {
  /**
   * 记录请求
   * @param method HTTP方法
   * @param path 请求路径
   * @param statusCode 状态码
   * @param duration 持续时间
   * @param labels 标签
   */
  recordRequest(
    method: string,
    path: string,
    statusCode: number,
    duration: number,
    labels?: Record<string, string>,
  ): void;

  /**
   * 记录数据库查询
   * @param operation 操作类型
   * @param table 表名
   * @param duration 持续时间
   * @param labels 标签
   */
  recordDatabaseQuery(
    operation: string,
    table: string,
    duration: number,
    labels?: Record<string, string>,
  ): void;

  /**
   * 记录缓存操作
   * @param operation 操作类型
   * @param key 缓存键
   * @param hit 是否命中
   * @param duration 持续时间
   * @param labels 标签
   */
  recordCacheOperation(
    operation: string,
    key: string,
    hit: boolean,
    duration: number,
    labels?: Record<string, string>,
  ): void;

  /**
   * 记录外部API调用
   * @param service 服务名称
   * @param endpoint 端点
   * @param statusCode 状态码
   * @param duration 持续时间
   * @param labels 标签
   */
  recordExternalApiCall(
    service: string,
    endpoint: string,
    statusCode: number,
    duration: number,
    labels?: Record<string, string>,
  ): void;
}

/**
 * 监控配置
 */
export interface MonitoringConfig {
  enabled: boolean;
  port: number;
  path: string;
  defaultLabels?: Record<string, string>;
  collectDefaultMetrics?: boolean;
  prefix?: string;
}

/**
 * 监控装饰器选项
 */
export interface MonitoringOptions {
  /**
   * 指标名称
   */
  name?: string;

  /**
   * 指标类型
   */
  type?: 'counter' | 'histogram' | 'summary' | 'gauge';

  /**
   * 标签
   */
  labels?: Record<string, string>;

  /**
   * 是否启用
   */
  enabled?: boolean;

  /**
   * 帮助文本
   */
  help?: string;
}
